/*
 * Copyright (c) Forge Development LLC and contributors
 * SPDX-License-Identifier: LGPL-2.1-only
 */

package net.neoforged.neoforge.fluids.capability;

import java.util.Objects;
import net.neoforged.neoforge.fluids.FluidStack;
import net.neoforged.neoforge.fluids.IFluidTank;
import net.neoforged.neoforge.transfer.ResourceHandler;
import net.neoforged.neoforge.transfer.ResourceHandlerUtil;
import net.neoforged.neoforge.transfer.fluid.FluidResource;
import net.neoforged.neoforge.transfer.fluid.FluidUtil;

/**
 * Implement this interface as a capability which should handle fluids, generally storing them in
 * one or more internal {@link IFluidTank} objects.
 * <p>
 * A reference implementation is provided {@link TileFluidHandler}.
 *
 * @deprecated Use {@link ResourceHandler} with a {@link FluidResource} instead. Code that is written against {@link IFluidHandler} but receives
 *             a {@code ResourceHandler<FluidResource>} can temporarily use {@link IFluidHandler#of} to ease migration.
 */
@Deprecated(since = "1.21.9", forRemoval = true)
public interface IFluidHandler {
    /**
     * Creates a wrapper around a {@link ResourceHandler}, to present it as a legacy {@link IFluidHandler}.
     *
     * <p>This class is intended to make migration easier for code that expects an {@link IFluidHandler}.
     *
     * @apiNote The {@link #fill} and {@link #drain} implementations will open new root transactions,
     *          so this wrapper cannot be used from a transactional context (such as {@link ResourceHandler#insert}).
     */
    static IFluidHandler of(ResourceHandler<FluidResource> handler) {
        Objects.requireNonNull(handler);

        return new FluidResourceHandlerAdapter(handler);
    }

    enum FluidAction {
        EXECUTE, SIMULATE;

        public boolean execute() {
            return this == EXECUTE;
        }

        public boolean simulate() {
            return this == SIMULATE;
        }
    }

    /**
     * Returns the number of fluid storage units ("tanks") available
     *
     * @return The number of tanks available
     * @deprecated Use {@link ResourceHandler#size()} instead.
     */
    @Deprecated(since = "1.21.9", forRemoval = true)
    int getTanks();

    /**
     * Returns the FluidStack in a given tank.
     *
     * <p>
     * <strong>IMPORTANT:</strong> This FluidStack <em>MUST NOT</em> be modified. This method is not for
     * altering internal contents. Any implementers who are able to detect modification via this method
     * should throw an exception. It is ENTIRELY reasonable and likely that the stack returned here will be a copy.
     * </p>
     *
     * <p>
     * <strong><em>SERIOUSLY: DO NOT MODIFY THE RETURNED FLUIDSTACK</em></strong>
     * </p>
     *
     * @param tank Tank to query.
     * @return FluidStack in a given tank. FluidStack.EMPTY if the tank is empty.
     * @deprecated Use {@link ResourceHandler#getAmountAsInt} and {@link ResourceHandler#getResource} instead.
     *             Alternatively use the {@link FluidUtil#getStack} helper.
     */
    @Deprecated(since = "1.21.9", forRemoval = true)
    FluidStack getFluidInTank(int tank);

    /**
     * Retrieves the maximum fluid amount for a given tank.
     *
     * @param tank Tank to query.
     * @return The maximum fluid amount held by the tank.
     * @deprecated Use {@link ResourceHandler#getCapacityAsInt} instead,
     *             passing {@link FluidResource#EMPTY} as the resource to retrieve a general tank limit.
     */
    @Deprecated(since = "1.21.9", forRemoval = true)
    int getTankCapacity(int tank);

    /**
     * This function is a way to determine which fluids can exist inside a given handler. General purpose tanks will
     * basically always return TRUE for this.
     *
     * @param tank  Tank to query for validity
     * @param stack Stack to test with for validity
     * @return TRUE if the tank can hold the FluidStack, not considering current state.
     *         (Basically, is a given fluid EVER allowed in this tank?) Return FALSE if the answer to that question is 'no.'
     * @deprecated Use {@link ResourceHandler#isValid} instead, however note that it doesn't make the same strong guarantees
     *             regarding how long a resource is valid. In other words: the result of {@code isValid} might change.
     */
    @Deprecated(since = "1.21.9", forRemoval = true)
    boolean isFluidValid(int tank, FluidStack stack);

    /**
     * Fills fluid into internal tanks, distribution is left entirely to the IFluidHandler.
     *
     * @param resource FluidStack representing the Fluid and maximum amount of fluid to be filled.
     * @param action   If SIMULATE, fill will only be simulated.
     * @return Amount of resource that was (or would have been, if simulated) filled.
     * @deprecated Use {@link ResourceHandler#insert} instead.
     */
    @Deprecated(since = "1.21.9", forRemoval = true)
    int fill(FluidStack resource, FluidAction action);

    /**
     * Drains fluid out of internal tanks, distribution is left entirely to the IFluidHandler.
     *
     * @param resource FluidStack representing the Fluid and maximum amount of fluid to be drained.
     * @param action   If SIMULATE, drain will only be simulated.
     * @return FluidStack representing the Fluid and amount that was (or would have been, if
     *         simulated) drained.
     * @deprecated Use {@link ResourceHandler#extract} instead.
     */
    @Deprecated(since = "1.21.9", forRemoval = true)
    FluidStack drain(FluidStack resource, FluidAction action);

    /**
     * Drains fluid out of internal tanks, distribution is left entirely to the IFluidHandler.
     * <p>
     * This method is not Fluid-sensitive.
     *
     * @param maxDrain Maximum amount of fluid to drain.
     * @param action   If SIMULATE, drain will only be simulated.
     * @return FluidStack representing the Fluid and amount that was (or would have been, if
     *         simulated) drained.
     * @deprecated Use {@link ResourceHandlerUtil#extractFirst} instead.
     */
    @Deprecated(since = "1.21.9", forRemoval = true)
    FluidStack drain(int maxDrain, FluidAction action);
}
